Core
Formstone Library core. Required for all plugins.
Use
Main
core.js
Formstone Object
The Formstone core is a dependency of all javascript based components and will contain a few global values, as well as a simple plugin factory. The global Formstone object has access to the following keys:
Key | Type | Description |
---|---|---|
$window |
object |
Reference to jQuery wrapped window |
window |
object |
Reference to original window |
$document |
object |
Reference to jQuery wrapped document |
document |
object |
Reference to original document |
$body |
object |
Reference to jQuery wrapped body tag |
Plugins |
object |
Contains all registered plugins |
support.file |
boolean |
File API support |
support.history |
boolean |
History API support, including push and pop state |
support.matchMedia |
boolean |
Match Media API support |
support.raf |
boolean |
Request Animation Frame API support |
support.touch |
boolean |
Touch event support |
support.transition |
boolean |
CSS3 Transition support |
userAgent |
string |
Raw user string |
isChrome |
boolean |
Browser is Chrome |
isFirefox |
boolean |
Browser is FireFox |
isSafari |
boolean |
Browser is Safari |
isMobile |
boolean |
Browser is Mobile |
isFirefoxMobile |
boolean |
Browser is FireFox Mobile |
transform |
string |
Prefixed transform property |
transition |
string |
Prefixed transition property |
windowWidth |
int |
Current window width |
windowHeight |
int |
Current window height |
User agent sniffing isn't always reliable or considered best practice - it should be used sparingly, if at all.
Plugin Factory
The Formstone.Plugin
factory function is used to define a plugin. The factory will use the provided namespace to register the plugin with jQuery. The plugin is then available like any other:
$(".target").plugin({
option: value
});
Plugin Types
There are two types of plugins that can be defined: Widget or Utility.
Widget
Widget plugins are implicitly tied to an element to enhance or change the interface. Examples of Widgets include input enhancements like Checkbox or Dropdown. A simple Widget might look like:
;(function ($, Formstone, undefined) {
function setUp() {
// this = document
}
function construct(data) {
// this = jQuery wrapped target element
// data = instance data
}
function destruct(data) {
// this = jQuery wrapped target element
// data = instance data
}
function reset(data) {
// this = jQuery wrapped target element
// data = instance data
}
// Register Plugin
var Plugin = Formstone.Plugin("namespace", {
widget: true,
defaults: {
option: value
},
classes: [
"visible"
],
methods: {
_setup : setup,
_construct : construct,
_destruct : destruct,
_resize : resize,
reset : reset
},
utilities: {
close: close
}
}),
// Localize References
Classes = Plugin.classes,
Events = Plugin.events,
Functions = Plugin.functions;
})(jQuery, Formstone);
As in the example above, Widgets can override three internal methods by pointing a key to the corresponding local function:
Method | Description |
---|---|
_setup |
Run once when document is ready, scoped to document |
_construct |
Run at initialization of each instance, scoped to specific instance |
_destruct |
Run at destruction of each instance, scoped to specific instance |
_resize |
Run on window resize, scoped to window |
When an instance is created or destroyed, the factory will automatically add or remove the instance's localized plugin data. This data is available as the first argument in any public method call, or by using the namespace to query for the data:
this.data("namespace");
Custom public methods can also be defined, provided their keys are not prefixed with an underscore (_
). The underscore signifies a core method and should be avoided when defining public methods. The factory will scope any public method call to the target instance, as well as provide it's plugin data as the first argument followed by any addition arguments:
$(".target").namespace("reset", 500);
A Widget can also operate as a singleton, like Lightbox or Tooltip. In this case, events are bound to the instance's target element, while DOM manipulations are tied to a single internal instance. This helps prevent unwanted duplication when the interface pattern calls for a single instance.
Utility
Utility plugins may interact with DOM nodes but are not necessarily tied to any specific elements. An example of a Utility is the media query event abstraction provided by Media Query. A simple Utility plugin might look like:
;(function ($, Formstone, undefined) {
function delegate() {
// Manually handle public methods
}
// Register Plugin
var Plugin = Formstone.Plugin("namespace", {
utilties: {
_delegate: delegate
}
}),
// Internal Defaults
Defaults = {
option : value
},
// Localize References
Document = Formstone.$document[0];
})(jQuery, Formstone);
A utility can override the default method delegation by pointing the _delegate
key to a custom function. The delegate function will need to manually handle any arguments passed. Otherwise, Utilities will use the same public method delegation system as Widgets.
$.namespace("reset", 500);
Plugin Object
Defining a plugin using the factory will return an object containing the follow keys:
Key | Type | Description |
---|---|---|
namespace |
string |
plugin namespace |
initialized |
boolean |
initialized state |
defaults |
object |
default options extended with initialization and local options |
functions |
object |
private utility functions |
methods |
object |
public methods |
utilities |
object |
public utility methods |
classes |
object |
namespaced classes strings |
events |
object |
namespaced event strings |
These values can then be localized in the scope of the plugin for optimal minimization:
var Plugin = Formstone.Plugin(“namespace”, {
...
}),
Defaults = Plugin.defaults,
Functions = Plugin.functions,
Methods = Plugin.methods,
Utilities = Plugin.utilities,
Classes = Plugin.classes,
Events = Plugin.events;
This may seem strangely redundant at first, however multi-dimensional objects do not minimize efficiently. This is also one reason standard prototypal inheritance is not used when building a plugin, however this is not to say a specific plugin could not contain locally scoped prototypes. Plugin design is always up to the developer, the factory simply provides a consistent, DRY approach to the basic plugin pattern.
Classes
The classes
object returned when defining a plugin will contain properly namespaced strings of both default and custom classes. Custom classes will become object keys, while the namespaced class will become the value:
var Plugin = Formstone.Plugin(“namespace”, {
...
classes: [
"visible",
"content"
],
...
});
var $element = $(Classes.content);
Key | Type | Value |
---|---|---|
base |
Default | .namespace |
element |
Default | .namespace-element |
visible |
Custom | .namespace-visible |
content |
Custom | .namespace-content |
The classes.raw
key will contain just the namespaced class without the leading '.', useful for building html:
html += '<div class="' + Classes.raw.content + '">';
Events
The events
object returned when defining a plugin will contain properly namespaced strings of both default and custom events. Custom events will become object keys, while the namespaced event will become the value:
var Plugin = Formstone.Plugin(“namespace”, {
...
events: [
"enable",
"disable"
],
...
});
data.$el.on(Events.click, onClick);
Key | Type | Value |
---|---|---|
namespace |
Default | .namespace |
blur |
Default | blur.namespace |
change |
Default | change.namespace |
click |
Default | click.namespace |
clickTouchStart |
Default | click.namespace touchstart.namespace |
dblClick |
Default | dblClick.namespace |
drag |
Default | drag.namespace |
dragEnd |
Default | dragend.namespace |
dragEnter |
Default | dragenter.namespace |
dragLeave |
Default | dragleave.namespace |
dragOver |
Default | dragover.namespace |
dragStart |
Default | dragstart.namespace |
drop |
Default | drop.namespace |
error |
Default | error.namespace |
focus |
Default | focus.namespace |
focusIn |
Default | focusin.namespace |
focusOut |
Default | focusout.namespace |
input |
Default | input.namespace |
keyDown |
Default | keydown.namespace |
keyPress |
Default | keypress.namespace |
keyUp |
Default | keyup.namespace |
load |
Default | load.namespace |
mouseDown |
Default | mousedown.namespace |
mouseEnter |
Default | mouseenter.namespace |
mouseLeave |
Default | mouseleave.namespace |
mouseMove |
Default | mousemove.namespace |
mouseOut |
Default | mouseout.namespace |
mouseOver |
Default | mouseover.namespace |
mouseUp |
Default | mouseup.namespace |
resize |
Default | resize.namespace |
scroll |
Default | scroll.namespace |
select |
Default | select.namespace |
touchCancel |
Default | touchcancel.namespace |
touchEnd |
Default | touchend.namespace |
touchLeave |
Default | touchleave.namespace |
touchMove |
Default | touchmove.namespace |
touchStart |
Default | touchstart.namespace |
transitionEnd |
Default | transitionEnd.namespace |
enable |
Custom | enable.namespace |
disable |
Custom | disable.namespace |
Methods
Plugin
Builds a plugin and registers it with jQuery.
Formstone.Plugin("namespace", { ... });
Parameters
Name | Type | Default | Description |
---|---|---|---|
namespace |
string |
Plugin namespace | |
settings |
object |
Plugin settings |